<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
    <title>11 Asynchronous Programming 3.2.11</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
    <link rel="stylesheet" href="../css/pdf.css" type="text/css" media="print" title="PDF" charset="utf-8"/>
    <script type="text/javascript">
function addJsClass() {
    var classes = document.body.className.split(" ");
    classes.push("js");
    document.body.className = classes.join(" ");
}
    </script>
</head>

<body class="body" onload="addJsClass();">
<div id="navigation">
    <div class="navTitle">
        
        The Grails Framework
    </div>
    <div class="navLinks">
        <ul>
            <li>
                <div id="nav-summary" onmouseover="toggleNavSummary(false)" onmouseout="toggleNavSummary(true)">
                    <a href="../guide/index.html" class="button">Table of contents</a>

                    <div id="nav-summary-childs" style="display:none;">
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/introduction.html"><strong>1</strong><span>Introduction</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/gettingStarted.html"><strong>2</strong><span>Getting Started</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/upgrading.html"><strong>3</strong><span>Upgrading</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/conf.html"><strong>4</strong><span>Configuration</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/commandLine.html"><strong>5</strong><span>The Command Line</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/profiles.html"><strong>6</strong><span>Application Profiles</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/GORM.html"><strong>7</strong><span>Object Relational Mapping (GORM)</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/theWebLayer.html"><strong>8</strong><span>The Web Layer</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/traits.html"><strong>9</strong><span>Traits</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/webServices.html"><strong>10</strong><span>Web Services</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/async.html"><strong>11</strong><span>Asynchronous Programming</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/validation.html"><strong>12</strong><span>Validation</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/services.html"><strong>13</strong><span>The Service Layer</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/staticTypeCheckingAndCompilation.html"><strong>14</strong><span>Static Type Checking And Compilation</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>15</strong><span>Testing</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/i18n.html"><strong>16</strong><span>Internationalization</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/security.html"><strong>17</strong><span>Security</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/plugins.html"><strong>18</strong><span>Plugins</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/spring.html"><strong>19</strong><span>Grails and Spring</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/hibernate.html"><strong>20</strong><span>Grails and Hibernate</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/scaffolding.html"><strong>21</strong><span>Scaffolding</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/deployment.html"><strong>22</strong><span>Deployment</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../guide/contributing.html"><strong>23</strong><span>Contributing to Grails</span></a>
                        </div>
                        
                    </div>
                </div>
            </li>
            <li class="separator selected">
                <a id="ref-button" onclick="localToggle(); return false;" href="#">Quick Reference</a>
            </li>
        </ul>
    </div>


</div>

<table id="colset" border="0" cellpadding="0" cellspacing="0">
    <tr>
        <td id="col1">
            <div id="main" class="corner-all">

                
                    <div class="toc-item prev-left"><a href="../guide/webServices.html">&lt;&lt; <strong>10</strong><span>Web Services</span></a></div>
                

                <span id='toggle-col1' class="toggle">(<a href="#" onclick="localToggle(); return false;">Quick Reference</a>)</span>

                
                    <div class="toc-item next-right"><a href="../guide/validation.html"><strong>12</strong><span>Validation</span> >></a></div>
                


                <div class="project">
                    <h1>11 Asynchronous Programming</h1>

                    <p><strong>Version:</strong> 3.2.11</p>
                </div>

                
                <div id="table-of-content">
                    <h2>Table of Contents</h2>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#promises"><strong>11.1</strong><span>Promises</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#rxjava"><strong>11.2</strong><span>Reactive Programming with RxJava</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#serverSentEvents"><strong>11.2.1</strong><span>Server Sent Events</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#rxGorm"><strong>11.2.2</strong><span>RxGORM</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#events"><strong>11.3</strong><span>Events</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#consuming"><strong>11.3.1</strong><span>Consuming Events</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#notifying"><strong>11.3.2</strong><span>Event Notification</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#annotations"><strong>11.3.3</strong><span>Reactor Spring Annotations</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#gormEvents"><strong>11.3.4</strong><span>Events from GORM</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#springEvents"><strong>11.3.5</strong><span>Events from Spring</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#asyncGorm"><strong>11.4</strong><span>Asynchronous GORM</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#asyncRequests"><strong>11.5</strong><span>Asynchronous Request Handling</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#asyncServletApi"><strong>11.6</strong><span>Servlet 3.0 Async</span></a>
                    </div>
                    
                </div>
                

                
<a name="8 Asynchronous Programming"><!-- Legacy link --></a>
<h1 id="async">11 Asynchronous Programming</h1>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>With modern hardware featuring multiple cores, many programming languages have been adding asynchronous, parallel programming APIs, Groovy being no exception.</p>
</div>
<div class="paragraph">
<p>The excellent <a href="http://www.gpars.org/guide/">GPars</a> project features a whole range of different APIs for asynchronous programming techniques including actors, promises, STM and data flow concurrency.</p>
</div>
<div class="paragraph">
<p>Added in Grails 2.3, the Async features of Grails aim to simplify concurrent programming within the framework and include the concept of Promises and a unified event model.</p>
</div>


<h2 id="promises">11.1 Promises</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/promises.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>A Promise is a concept being embraced by many concurrency frameworks. They are similar to <code>java.util.concurrent.Future</code> instances, but include a more user friendly exception handling model, useful features like chaining and the ability to attach listeners.</p>
</div>
<div class="sect2">
<h3 id="_promise_basics">Promise Basics</h3>
<div class="paragraph">
<p>In Grails the <code>grails.async.Promises</code> class provides the entry point to the Promise API:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.Promises.*</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>To create promises you can use the <code>task</code> method, which returns an instance of the <code>grails.async.Promise</code> interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> p1 = task { <span class="integer">2</span> * <span class="integer">2</span> }
<span class="keyword">def</span> p2 = task { <span class="integer">4</span> * <span class="integer">4</span> }
<span class="keyword">def</span> p3 = task { <span class="integer">8</span> * <span class="integer">8</span> }
<span class="keyword">assert</span> [<span class="integer">4</span>,<span class="integer">16</span>,<span class="integer">64</span>] == waitAll(p1, p2, p3)</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>waitAll</code> method waits synchronously, blocking the current thread, for all of the concurrent tasks to complete and returns the results.</p>
</div>
<div class="paragraph">
<p>If you prefer not to block the current thread you can use the <code>onComplete</code> method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">onComplete([p1,p2,p3]) { <span class="predefined-type">List</span> results -&gt;
   <span class="keyword">assert</span> [<span class="integer">4</span>,<span class="integer">16</span>,<span class="integer">64</span>] == results
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>waitAll</code> method will throw an exception if an error occurs executing one of the promises. The originating exception will be thrown. The <code>onComplete</code> method, however, will simply not execute the passed closure if an exception occurs. You can register an <code>onError</code> listener if you wish to handle exceptions without blocking:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">onError([p1,p2,p3]) { <span class="predefined-type">Throwable</span> t -&gt;
   println <span class="string"><span class="delimiter">&quot;</span><span class="content">An error occured </span><span class="inline"><span class="inline-delimiter">${</span>t.message<span class="inline-delimiter">}</span></span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you have just a single long running promise then the <code>grails.async.Promise</code> interface provides a similar API on the promise itself. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">java.util.concurrent.TimeUnit.*</span>
<span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.Promises.*</span>

Promise p = task {
        <span class="comment">// Long running task</span>
}
p.onError { <span class="predefined-type">Throwable</span> err -&gt;
        println <span class="string"><span class="delimiter">&quot;</span><span class="content">An error occured </span><span class="inline"><span class="inline-delimiter">${</span>err.message<span class="inline-delimiter">}</span></span><span class="delimiter">&quot;</span></span>
}
p.onComplete { result -&gt;
    println <span class="string"><span class="delimiter">&quot;</span><span class="content">Promise returned </span><span class="inline"><span class="inline-delimiter">$</span>result</span><span class="delimiter">&quot;</span></span>
}
<span class="comment">// block until result is called</span>
<span class="keyword">def</span> result = p.get()
<span class="comment">// block for the specified time</span>
<span class="keyword">def</span> result = p.get(<span class="integer">1</span>,MINUTES)</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_promise_chaining">Promise Chaining</h3>
<div class="paragraph">
<p>It is possible to chain several promises and wait for the chain to complete using the <code>then</code> method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="directive">final</span> polish = { ... }
<span class="directive">final</span> transform = { ... }
<span class="directive">final</span> save = { ... }
<span class="directive">final</span> notify = { ... }

Promise promise = task {
    <span class="comment">// long running task</span>
}
promise.then polish then transform then save then {
        <span class="comment">// notify end result</span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If an exception occurs at any point in the chain it will be propagated back to the caller and the next step in the chain will not be called.</p>
</div>
</div>
<div class="sect2">
<h3 id="_promise_lists_and_maps">Promise Lists and Maps</h3>
<div class="paragraph">
<p>Grails' async API also features the concept of a promise lists and maps. These are represented by the <code>grails.async.PromiseList</code> and <code>grails.async.PromiseMap</code> classes respectively.</p>
</div>
<div class="paragraph">
<p>The easiest way to create a promise list or map is via the <code>tasks</code> method of the <code>Promises</code> class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.Promises.*</span>

<span class="keyword">def</span> promiseList = tasks([{ <span class="integer">2</span> * <span class="integer">2</span> }, { <span class="integer">4</span> * <span class="integer">4</span>}, { <span class="integer">8</span> * <span class="integer">8</span> }])

<span class="keyword">assert</span> [<span class="integer">4</span>,<span class="integer">16</span>,<span class="integer">64</span>] == promiseList.get()</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>tasks</code> method, when passed a list of closures, returns a <code>PromiseList</code>. You can also construct a <code>PromiseList</code> manually:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.async.*</span>

<span class="keyword">def</span> list = <span class="keyword">new</span> PromiseList()
list &lt;&lt; { <span class="integer">2</span> * <span class="integer">2</span> }
list &lt;&lt; { <span class="integer">4</span> * <span class="integer">4</span> }
list &lt;&lt; { <span class="integer">8</span> * <span class="integer">8</span> }
list.onComplete { <span class="predefined-type">List</span> results -&gt;
  <span class="keyword">assert</span> [<span class="integer">4</span>,<span class="integer">16</span>,<span class="integer">64</span>] == results
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The <code>PromiseList</code> class does not implement the java.util.List interface, but instead returns a java.util.List from the get() method
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Working with <code>PromiseMap</code> instances is largely similar. Again you can either use the <code>tasks</code> method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.Promises.*</span>

<span class="keyword">def</span> promiseList = tasks <span class="key">one</span>:{ <span class="integer">2</span> * <span class="integer">2</span> },
                        <span class="key">two</span>:{ <span class="integer">4</span> * <span class="integer">4</span>},
                        <span class="key">three</span>:{ <span class="integer">8</span> * <span class="integer">8</span> }

<span class="keyword">assert</span> [<span class="key">one</span>:<span class="integer">4</span>,<span class="key">two</span>:<span class="integer">16</span>,<span class="key">three</span>:<span class="integer">64</span>] == promiseList.get()</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or construct a <code>PromiseMap</code> manually:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.async.*</span>

<span class="keyword">def</span> map = <span class="keyword">new</span> PromiseMap()
map[<span class="string"><span class="delimiter">'</span><span class="content">one</span><span class="delimiter">'</span></span>] = { <span class="integer">2</span> * <span class="integer">2</span> }
map[<span class="string"><span class="delimiter">'</span><span class="content">two</span><span class="delimiter">'</span></span>] = { <span class="integer">4</span> * <span class="integer">4</span> }
map[<span class="string"><span class="delimiter">'</span><span class="content">three</span><span class="delimiter">'</span></span>] = { <span class="integer">8</span> * <span class="integer">8</span> }
map.onComplete { <span class="predefined-type">Map</span> results -&gt;
  <span class="keyword">assert</span> [<span class="key">one</span>:<span class="integer">4</span>,<span class="key">two</span>:<span class="integer">16</span>,<span class="key">three</span>:<span class="integer">64</span>] == results
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_promises_vs_webpromises">Promises vs. WebPromises</h3>
<div class="paragraph">
<p>Since Grails 3.2.7, there are two factory classes for <code>Promise</code> instances. They are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>grails.async.Promises</code> - general purpose and not web specified</p>
</li>
<li>
<p><code>grails.async.web.WebPromises</code> - designed for creating asynchronous responses.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Typically you use <code>WebPromises</code> within a controller, and its behaviour differs because Grails will automatically turn the request into an Servlet 3.x async request to execute the tasks created by <code>WebPromises</code>.</p>
</div>
<div class="paragraph">
<p>The <code>Promises</code> factory class on the other hand is not web specific and will not create async requests.</p>
</div>
<div class="paragraph">
<p>This also means that within the body of the task for <code>WebPromises</code> you can use controller methods such as <code>render</code> etc. For example the following works with <code>WebPromises</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.web.WebPromises.*</span>
<span class="type">class</span> <span class="class">HelloController</span> {

    <span class="keyword">def</span> <span class="function">sayHello</span>(<span class="predefined-type">String</span> message) {
       task {
           render <span class="string"><span class="delimiter">&quot;</span><span class="content">Hello </span><span class="inline"><span class="inline-delimiter">$</span>message</span><span class="delimiter">&quot;</span></span>
       }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>However, the above will fail with the regular <code>Promises</code> class.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
In versions of Grails prior to 3.2.7, <code>Promises</code> used to allow the use of <code>render</code> and other controller methods, however this was unsafe as the request thread may have finished prior to the task executing leading to unexpected errors.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_promise_factories">Promise Factories</h3>
<div class="paragraph">
<p>The <code>Promises</code> class uses a <code>grails.async.PromiseFactory</code> instance to create <code>Promise</code> instances.</p>
</div>
<div class="paragraph">
<p>The default implementation uses <a href="http://projectreactor.io">Project Reactor</a> and is called <code>org.grails.async.factory.reactor.ReactorPromiseFactory</code>, however it is possible to swap implementations by setting the <code>Promises.promiseFactory</code> variable.</p>
</div>
<div class="paragraph">
<p>One common use case for this is unit testing, typically you do not want promises to execute asynchronously during unit tests, as this makes tests harder to write. For this purpose Grails ships with a <code>org.grails.async.factory.SynchronousPromiseFactory</code> instance that makes it easier to test promises:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">org.grails.async.factory.*</span>
<span class="keyword">import</span> <span class="include">grails.async.*</span>

Promises.promiseFactory = <span class="keyword">new</span> SynchronousPromiseFactory()</code></pre>
</div>
</div>
<div class="paragraph">
<p>Using the <code>PromiseFactory</code> mechanism it is theoretically possible to plug in other concurrency libraries into the Grails framework. For this you need to override the two interfaces <code>grails.async.Promise</code> and <code>grails.async.PromiseFactory</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_delegateasync_transformation">DelegateAsync Transformation</h3>
<div class="paragraph">
<p>It is quite common to require both synchronous and asynchronous versions of the same API. Developing both can result in a maintenance problem as typically the asynchronous API would simply delegate to the synchronous version.</p>
</div>
<div class="paragraph">
<p>The <code>DelegateAsync</code> transformation is designed to mitigate this problem by transforming any synchronous API into an asynchronous one.</p>
</div>
<div class="paragraph">
<p>For example, consider the following service:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">BookService</span> {
    <span class="predefined-type">List</span>&lt;<span class="predefined-type">Book</span>&gt; findBooks(<span class="predefined-type">String</span> title) {
      <span class="comment">// implementation</span>
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>findBooks</code> method executes synchronously in the same thread as the caller. To make an asynchronous version of this API you can define another class as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.async.*</span>

<span class="type">class</span> <span class="class">AsyncBookService</span> {
   <span class="annotation">@DelegateAsync</span> BookService bookService
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>DelegateAsync</code> transformation will automatically add a new method that looks like the following to the <code>AsyncBookService</code> class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">Promise&lt;<span class="predefined-type">List</span>&lt;<span class="predefined-type">Book</span>&gt;&gt; findBooks(<span class="predefined-type">String</span> title) {
    Promises.task {
       bookService.findBooks(title)
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>As you see the transform adds equivalent methods that return a Promise and execute asynchronously.</p>
</div>
<div class="paragraph">
<p>The <code>AsyncBookService</code> can then be injected into other controllers and services and used as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">AsyncBookService asyncBookService
<span class="keyword">def</span> <span class="function">findBooks</span>(<span class="predefined-type">String</span> title) {
    asyncBookService.findBooks(title)
       .onComplete { <span class="predefined-type">List</span> results -&gt;
          println <span class="string"><span class="delimiter">&quot;</span><span class="content">Books = </span><span class="inline"><span class="inline-delimiter">${</span>results<span class="inline-delimiter">}</span></span><span class="delimiter">&quot;</span></span>
       }
}</code></pre>
</div>
</div>
</div>


<h2 id="rxjava">11.2 Reactive Programming with RxJava</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/rxjava.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Since Grails 3.2, you can use <a href="https://github.com/ReactiveX/RxJava">RxJava</a> to write reactive logic in your Grails controllers that leverages the underlying containers asynchronous processing capabilities.</p>
</div>
<div class="paragraph">
<p>To get started simply declare a dependency on the plugin in <code>build.gradle</code>:</p>
</div>
<div class="listingblock">
<div class="title">build.gradle</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">dependencies {
    ...
    compile <span class="string"><span class="delimiter">'</span><span class="content">org.grails.plugins:rxjava</span><span class="delimiter">'</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can then return <code>rx.Observable</code> as a return value from any controller and Grails will automatically apply the following steps:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Create a new asynchronous request</p>
</li>
<li>
<p>Spawn a new thread that subscribes to the observable</p>
</li>
<li>
<p>When the observable omits a result process the result using the <a href="../ref/Controllers/respond.html">respond</a> method.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>For more detailed instructions on how to use the RxJava plugin see the <a href="https://grails-plugins.github.io/grails-rxjava/latest/">user guide documentation</a> for the plugin.</p>
</div>


<h2 id="serverSentEvents">11.2.1 Server Sent Events</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/rxjava/serverSentEvents.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Server-sent events (SSE) is a technology where a browser receives automatic updates from a server via HTTP connection. The Server-Sent Events EventSource API is standardized as part of HTML5 by the W3C.</p>
</div>
<div class="paragraph">
<p>The <a href="https://grails-plugins.github.io/grails-rxjava/latest/">RxJava plugin</a> adds support for SSE to Grails making it simple to write controllers that maintain continuous non-blocking communication with a JavaScript client.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">index</span>() {

    rx.stream { Subscriber subscriber -&gt; <i class="conum" data-value="1"></i><b>(1)</b>
       <span class="keyword">for</span>(i <span class="keyword">in</span> (<span class="integer">0</span>..<span class="integer">5</span>)) {
           <span class="keyword">if</span>(i % <span class="integer">2</span> == <span class="integer">0</span>) {
               subscriber.onNext(
                   rx.render(<span class="string"><span class="delimiter">&quot;</span><span class="content">Tick</span><span class="delimiter">&quot;</span></span>) <i class="conum" data-value="2"></i><b>(2)</b>
               )
           }
           <span class="keyword">else</span> {
               subscriber.onNext(
                   rx.render(<span class="string"><span class="delimiter">&quot;</span><span class="content">Tock</span><span class="delimiter">&quot;</span></span>)
               )

           }
           sleep <span class="integer">1000</span> <i class="conum" data-value="3"></i><b>(3)</b>
       }
       subscriber.onCompleted() <i class="conum" data-value="4"></i><b>(4)</b>
   }
}</code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>Call the <code>stream</code> method passing a closure that accepts an <code>rx.Subscriber</code> to start sending events</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>Emit a one or many items using <code>onNext</code></td>
</tr>
<tr>
<td><i class="conum" data-value="3"></i><b>3</b></td>
<td>Call <code>sleep</code> to simulate a slow request</td>
</tr>
<tr>
<td><i class="conum" data-value="4"></i><b>4</b></td>
<td>Call <code>onCompleted</code> to complete the request</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For more detailed instructions on how to use SSE and the RxJava plugin see the <a href="https://grails-plugins.github.io/grails-rxjava/latest/">user guide documentation</a> for the plugin.</p>
</div>


<h2 id="rxGorm">11.2.2 RxGORM</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/rxjava/rxGorm.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p><a href="http://gorm.grails.org/6.0.x/rx/manual/">RxGORM</a> is new implementation of GORM that has the following goals:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Reactive</p>
</li>
<li>
<p>Non-blocking</p>
</li>
<li>
<p>Stateless</p>
</li>
<li>
<p>Simple</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>RxGORM, unlike the <a href="async.html#asyncGorm">Asynchronous GORM</a> implementation, aims to be truly non-blocking, down to the driver level.</p>
</div>
<div class="paragraph">
<p>The following is an example of RxGORM in action:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="predefined-type">Book</span>.get(id)
    .subscribe { <span class="predefined-type">Book</span> <span class="local-variable">it</span> -&gt;
    println <span class="string"><span class="delimiter">&quot;</span><span class="content">Title = </span><span class="inline"><span class="inline-delimiter">${</span><span class="local-variable">it</span>.title<span class="inline-delimiter">}</span></span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can combine RxGORM with the <a href="https://grails-plugins.github.io/grails-rxjava/latest">RxJava</a> plugin to implement reactive responses from Grails controllers. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">show</span>() {
        <span class="comment">// returns an rx.Observable</span>
    <span class="predefined-type">Book</span>.get(params.id?.toString())
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>For more information on how to use RxGORM, see the <a href="http://gorm.grails.org/6.0.x/rx/manual/">RxGORM user guide</a>.</p>
</div>

<a name="4.3 Hooking into Events"><!-- Legacy link --></a>
<h2 id="events">11.3 Events</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/events.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Grails 3.0 introduces a new Events API based on <a href="https://github.com/reactor/reactor">Reactor</a>.</p>
</div>
<div class="paragraph">
<p>All services and controllers in Grails 3.0 implement the <a href="http://docs.grails.org/3.2.11/api/grails/events/Events.html">Events</a> trait.</p>
</div>
<div class="paragraph">
<p>The <code>Events</code> trait allows the ability to consume and publish events that are handled by Reactor.</p>
</div>
<div class="paragraph">
<p>The default Reactor configuration utilises a thread pool backed event bus. You can however configure Reactor within <code>application.yml</code>, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="key">reactor</span>:
    <span class="key">dispatchers</span>:
        <span class="keyword">default</span>: myExecutor
        <span class="key">myExecutor</span>:
            <span class="key">type</span>: threadPoolExecutor
            <span class="key">size</span>: <span class="integer">5</span>
            <span class="key">backlog</span>: <span class="integer">2048</span></code></pre>
</div>
</div>


<h2 id="consuming">11.3.1 Consuming Events</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/events/consuming.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>There are several ways to consume an event. As mentioned previously services and controllers implement the <a href="http://docs.grails.org/3.2.11/api/grails/events/Events.html">Events</a> trait.</p>
</div>
<div class="paragraph">
<p>The <code>Events</code> trait provides several methods to register event consumers. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">on(<span class="string"><span class="delimiter">&quot;</span><span class="content">myEvent</span><span class="delimiter">&quot;</span></span>) {
    println <span class="string"><span class="delimiter">&quot;</span><span class="content">Event fired!</span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that if you wish a class (other than a controller or service) to be an event consumer you simply have to implement the <code>Events</code> trait and ensure the class is registered as a Spring bean.</p>
</div>
<div class="paragraph">
<p>For example given the following class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.events.*</span>
<span class="keyword">import</span> <span class="include">javax.annotation.*</span>

<span class="type">class</span> <span class="class">MyClass</span> <span class="directive">implements</span> Events {

        <span class="annotation">@PostConstruct</span>
        <span class="type">void</span> init() {
                on(<span class="string"><span class="delimiter">&quot;</span><span class="content">myEvent</span><span class="delimiter">&quot;</span></span>) {
                    println <span class="string"><span class="delimiter">&quot;</span><span class="content">Event fired!</span><span class="delimiter">&quot;</span></span>
                }
        }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can override <code>doWithSpring</code> in your <code>Application</code> class to register it as a Spring bean (or annotate it with <code>Component</code>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">Closure doWithSpring() {
        {-&gt;
                    myClass(MyClass)
        }
    }</code></pre>
</div>
</div>


<h2 id="notifying">11.3.2 Event Notification</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/events/notifying.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>The <code>Events</code> trait also provides methods for notifying of events. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">notify <span class="string"><span class="delimiter">&quot;</span><span class="content">myEvent</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">myData</span><span class="delimiter">&quot;</span></span>
sendAndReceive <span class="string"><span class="delimiter">&quot;</span><span class="content">myEvent</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">myData</span><span class="delimiter">&quot;</span></span>, {
    println <span class="string"><span class="delimiter">&quot;</span><span class="content">Got response!</span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>


<h2 id="annotations">11.3.3 Reactor Spring Annotations</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/events/annotations.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Reactor provides a few useful annotations that can be used for declaratively consuming events in a Grails service.</p>
</div>
<div class="paragraph">
<p>To declare an event consumer use the <code>Consumer</code> annotation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">reactor.spring.context.annotation.*</span>

<span class="annotation">@Consumer</span>
<span class="type">class</span> <span class="class">MyService</span> {

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then to register to listen for an event use the <code>Selector</code> annotation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">reactor.spring.context.annotation.*</span>

<span class="annotation">@Consumer</span>
<span class="type">class</span> <span class="class">MyService</span> {
        <span class="annotation">@Selector</span>(<span class="string"><span class="delimiter">'</span><span class="content">myEvent</span><span class="delimiter">'</span></span>)
        <span class="type">void</span> myEventListener(<span class="predefined-type">Object</span> data) {
                println <span class="string"><span class="delimiter">&quot;</span><span class="content">GOT EVENT </span><span class="inline"><span class="inline-delimiter">$</span>data</span><span class="delimiter">&quot;</span></span>
        }
}</code></pre>
</div>
</div>


<h2 id="gormEvents">11.3.4 Events from GORM</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/events/gormEvents.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>GORM defines a <a href="http://grails.github.io/grails-data-mapping/latest/api/org/grails/datastore/mapping/engine/event/package-summary.html">number of useful events</a> that you can listen for.</p>
</div>
<div class="paragraph">
<p>Each event is translated into a key that starts with <code>gorm:</code>. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">org.grails.datastore.mapping.engine.event.*</span>
...

on(<span class="string"><span class="delimiter">&quot;</span><span class="content">gorm:preInsert</span><span class="delimiter">&quot;</span></span>) { PreInsertEvent event -&gt;
        println <span class="string"><span class="delimiter">&quot;</span><span class="content">GOT EVENT </span><span class="inline"><span class="inline-delimiter">$</span>event</span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
These events are triggered asynchronously, and so cannot cancel or manipulate the persistence operations. If you want to do that see the section on <a href="http://gorm.grails.org/6.0.x/hibernate/manual/index.html#eventsAutoTimestamping">Events &amp; Auto Timestamping</a> in the GORM docs
</td>
</tr>
</table>
</div>


<h2 id="springEvents">11.3.5 Events from Spring</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/events/springEvents.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Spring also fires a number of useful events. All events in the <code>org.springframework</code> package are prefixed with <code>spring:</code>.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">org.springframework.web.context.support.*</span>
<span class="keyword">import</span> <span class="include">org.springframework.boot.context.event.*</span>
...

on(<span class="string"><span class="delimiter">&quot;</span><span class="content">spring:applicationStarted</span><span class="delimiter">&quot;</span></span>) { ApplicationStartedEvent event -&gt;
        <span class="comment">// fired when the application starts</span>
}

on(<span class="string"><span class="delimiter">&quot;</span><span class="content">spring:servletRequestHandled</span><span class="delimiter">&quot;</span></span>) { RequestHandledEvent event -&gt;
        <span class="comment">// fired each time a request is handled</span>
}</code></pre>
</div>
</div>


<h2 id="asyncGorm">11.4 Asynchronous GORM</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/asyncGorm.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Since Grails 2.3, GORM features an asynchronous programming model that works across all supported datastores (Hibernate, MongoDB etc.).</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Although GORM executes persistence operations asynchronously, these operations still block as the underlying database drivers are not asynchronous. Asynchornous GORM is designed to allow you to isolate these blocking operations onto a separate thread you can scale and control allowing your controller layer to remain non-blocking.
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="_async_namespace">Async Namespace</h3>
<div class="paragraph">
<p>The Asynchronous GORM API is available on every domain class via the <code>async</code> namespace.</p>
</div>
<div class="paragraph">
<p>For example, the following code listing reads 3 objects from the database asynchronously:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.Promises.*</span>

<span class="keyword">def</span> p1 = Person.async.get(<span class="integer">1L</span>)
<span class="keyword">def</span> p2 = Person.async.get(<span class="integer">2L</span>)
<span class="keyword">def</span> p3 = Person.async.get(<span class="integer">3L</span>)
<span class="keyword">def</span> results = waitAll(p1, p2, p3)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Using the <code>async</code> namespace, all the regular GORM methods are available (even dynamic finders), but instead of executing synchronously, the query is run in the background and a <code>Promise</code> instance is returned.</p>
</div>
<div class="paragraph">
<p>The following code listing shows a few common examples of GORM queries executed asynchronously:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.Promises.*</span>

Person.async.list().onComplete { <span class="predefined-type">List</span> results -&gt;
  println <span class="string"><span class="delimiter">&quot;</span><span class="content">Got people = </span><span class="inline"><span class="inline-delimiter">${</span>results<span class="inline-delimiter">}</span></span><span class="delimiter">&quot;</span></span>
}
<span class="keyword">def</span> p = Person.async.getAll(<span class="integer">1L</span>, <span class="integer">2L</span>, <span class="integer">3L</span>)
<span class="predefined-type">List</span> results = p.get()

<span class="keyword">def</span> p1 = Person.async.findByFirstName(<span class="string"><span class="delimiter">&quot;</span><span class="content">Homer</span><span class="delimiter">&quot;</span></span>)
<span class="keyword">def</span> p2 = Person.async.findByFirstName(<span class="string"><span class="delimiter">&quot;</span><span class="content">Bart</span><span class="delimiter">&quot;</span></span>)
<span class="keyword">def</span> p3 = Person.async.findByFirstName(<span class="string"><span class="delimiter">&quot;</span><span class="content">Barney</span><span class="delimiter">&quot;</span></span>)
results = waitAll(p1, p2, p3)</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_async_and_the_session">Async and the Session</h3>
<div class="paragraph">
<p>When using GORM async each promise is executed in a different thread. Since the Hibernate session is not concurrency safe, a new session is bound per thread.</p>
</div>
<div class="paragraph">
<p>This is an important consideration when using GORM async (particularly with Hibernate as the persistence engine). The objects returned from asynchronous queries will be detached entities.</p>
</div>
<div class="paragraph">
<p>This means you cannot save objects returned from asynchronous queries without first merging them back into session. For example the following will not work:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> promise = Person.async.findByFirstName(<span class="string"><span class="delimiter">&quot;</span><span class="content">Homer</span><span class="delimiter">&quot;</span></span>)
<span class="keyword">def</span> person = promise.get()
person.firstName = <span class="string"><span class="delimiter">&quot;</span><span class="content">Bart</span><span class="delimiter">&quot;</span></span>
person.save()</code></pre>
</div>
</div>
<div class="paragraph">
<p>Instead you need to merge the object with the session bound to the calling thread. The above code needs to be written as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> promise = Person.async.findByFirstName(<span class="string"><span class="delimiter">&quot;</span><span class="content">Homer</span><span class="delimiter">&quot;</span></span>)
<span class="keyword">def</span> person = promise.get()
person = person.merge()
person.firstName = <span class="string"><span class="delimiter">&quot;</span><span class="content">Bart</span><span class="delimiter">&quot;</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that <code>merge()</code> is called first because it may refresh the object from the cache or database, which would result in the change being lost. In general it is not recommended to read and write objects in different threads and you should avoid this technique unless absolutely necessary.</p>
</div>
<div class="paragraph">
<p>Finally, another issue with detached objects is that association lazy loading <strong>will not</strong> work and you will encounter <code>LazyInitializationException</code> errors if you do so. If you plan to access the associated objects of those returned from asynchronous queries you should use eager queries (which is recommended anyway to avoid N+1 problems).</p>
</div>
</div>
<div class="sect2">
<h3 id="_multiple_asynchronous_gorm_calls">Multiple Asynchronous GORM calls</h3>
<div class="paragraph">
<p>As discussed in the previous section you should avoid reading and writing objects in different threads as merging tends to be inefficient.</p>
</div>
<div class="paragraph">
<p>However, if you wish to do more complex GORM work asynchronously then the GORM async namespace provides a <code>task</code> method that makes this possible. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> promise = Person.async.task {
    withTransaction {
       <span class="keyword">def</span> person = findByFirstName(<span class="string"><span class="delimiter">&quot;</span><span class="content">Homer</span><span class="delimiter">&quot;</span></span>)
       person.firstName = <span class="string"><span class="delimiter">&quot;</span><span class="content">Bart</span><span class="delimiter">&quot;</span></span>
       person.save(<span class="key">flush</span>:<span class="predefined-constant">true</span>)
    }
}

Person updatedPerson = promise.get()</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that the GORM <code>task</code> method differs from the static <code>Promises.task</code> method in that it deals with binding a new session to the asynchronous thread for you. If you do not use the GORM version and do asynchronous work with GORM then you need to do this manually. Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.Promises.*</span>

<span class="keyword">def</span> promise = task {
    Person.withNewSession {
            <span class="comment">// your logic here</span>
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_async_detachedcriteria">Async DetachedCriteria</h3>
<div class="paragraph">
<p>The <code>DetachedCriteria</code> class also supports the <code>async</code> namespace. For example you can do the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">DetachedCriteria query = Person.where {
    lastName == <span class="string"><span class="delimiter">&quot;</span><span class="content">Simpson</span><span class="delimiter">&quot;</span></span>
}

<span class="keyword">def</span> promise = query.async.list()</code></pre>
</div>
</div>
</div>


<h2 id="asyncRequests">11.5 Asynchronous Request Handling</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/asyncRequests.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>If you are deploying to a Servlet 3.0 container such as Tomcat 7 and above then it is possible to deal with responses asynchronously.</p>
</div>
<div class="paragraph">
<p>In general for controller actions that execute quickly there is little benefit in handling requests asynchronously. However, for long running controller actions it is extremely beneficial.</p>
</div>
<div class="paragraph">
<p>The reason being that with an asynchronous / non-blocking response, the one thread == one request == one response relationship is broken. The container can keep a client response open and active, and at the same time return the thread back to the container to deal with another request, improving scalability.</p>
</div>
<div class="paragraph">
<p>For example, if you have 70 available container threads and an action takes a minute to complete, if the actions are not executed in a non-blocking fashion the likelihood of all 70 threads being occupied and the container not being able to respond is quite high and you should consider asynchronous request processing.</p>
</div>
<div class="paragraph">
<p>Since Grails 2.3, Grails features a simplified API for creating asynchronous responses built on the <code>Promise</code> mechanism discussed previously.</p>
</div>
<div class="sect3">
<h4 id="_async_models">Async Models</h4>
<div class="paragraph">
<p>A typical activity in a Grails controller is to produce a model (a map of key/value pairs) that can be rendered by a view.</p>
</div>
<div class="paragraph">
<p>If the model takes a while to produce then the server could arrive at a blocking state, impacting scalability. You tell Grails to build the model asynchronously by returning a <code>grails.async.PromiseMap</code> via the <code>Promises.tasks</code> method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.Promises.*</span>
...
def index() {
   tasks <span class="key">books</span>: <span class="predefined-type">Book</span>.async.list(),
         <span class="key">totalBooks</span>: <span class="predefined-type">Book</span>.async.count(),
         <span class="key">otherValue</span>: {
           <span class="comment">// do hard work</span>
         }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Grails will handle the response asynchronously, waiting for the promises to complete before rendering the view. The equivalent synchronous action of the above is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">index</span>() {
    <span class="keyword">def</span> otherValue = ...
        [ <span class="key">books</span>: <span class="predefined-type">Book</span>.list() ,
          <span class="key">totalBooks</span>: <span class="predefined-type">Book</span>.count(),
          <span class="key">otherValue</span>: otherValue  ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can even render different view by passing the <code>PromiseMap</code> to the <code>model</code> attribute of the <code>render</code> method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.Promises.*</span>
...
def index() {
   render <span class="key">view</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">myView</span><span class="delimiter">&quot;</span></span>, <span class="key">model</span>: tasks( <span class="key">one</span>:{ <span class="integer">2</span> * <span class="integer">2</span> },
                                       <span class="key">two</span>:{ <span class="integer">3</span> * <span class="integer">3</span> } )
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_async_response_rendering">Async Response Rendering</h4>
<div class="paragraph">
<p>You can also write to the response asynchronously using promises in Grails 2.3 and above and the <code>WebPromises</code> class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">static</span> <span class="include">grails.async.web.WebPromises.*</span>
<span class="type">class</span> <span class="class">StockController</span> {

    <span class="keyword">def</span> <span class="function">stock</span>(<span class="predefined-type">String</span> ticker) {
       task {
           ticker = ticker ?: <span class="string"><span class="delimiter">'</span><span class="content">GOOG</span><span class="delimiter">'</span></span>
           <span class="keyword">def</span> url = <span class="keyword">new</span> <span class="predefined-type">URL</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">http://download.finance.yahoo.com/d/quotes.csv?s=</span><span class="inline"><span class="inline-delimiter">${</span>ticker<span class="inline-delimiter">}</span></span><span class="content">&amp;f=nsl1op&amp;e=.csv</span><span class="delimiter">&quot;</span></span>)
           <span class="predefined-type">Double</span> price = url.text.split(<span class="string"><span class="delimiter">'</span><span class="content">,</span><span class="delimiter">'</span></span>)[-<span class="integer">1</span>] <span class="keyword">as</span> <span class="predefined-type">Double</span>
           render <span class="string"><span class="delimiter">&quot;</span><span class="content">ticker: </span><span class="inline"><span class="inline-delimiter">$</span>ticker</span><span class="content">, price: </span><span class="char">\$</span><span class="content">price</span><span class="delimiter">&quot;</span></span>
       }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above example using Yahoo Finance to query stock prices, executing asynchronously and only rendering the response once the result has been obtained. This is done by returning a <code>Promise</code> instance from the controller action.</p>
</div>
<div class="paragraph">
<p>If the Yahoo URL is unresponsive the original request thread will not be blocked and the container will not become unresponsive.</p>
</div>
</div>


<h2 id="asyncServletApi">11.6 Servlet 3.0 Async</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/async/asyncServletApi.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>In addition to the higher level async features discussed earlier in the section, you can access the raw Servlet 3.0 asynchronous API from a Grails application.</p>
</div>
<div class="sect3">
<h4 id="_servlet_3_0_asynchronous_rendering">Servlet 3.0 Asynchronous Rendering</h4>
<div class="paragraph">
<p>You can render content (templates, binary data etc.) in an asynchronous manner by calling the <code>startAsync</code> method which returns an instance of the Servlet 3.0 <code>AsyncContext</code>. Once you have a reference to the <code>AsyncContext</code> you can use Grails' regular render method to render content:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">index</span>() {
    <span class="keyword">def</span> ctx = startAsync()
    ctx.start {
        <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">The Stand</span><span class="delimiter">&quot;</span></span>).save()
        render <span class="key">template</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">books</span><span class="delimiter">&quot;</span></span>, <span class="key">model</span>:[<span class="key">books</span>:<span class="predefined-type">Book</span>.list()]
        ctx.complete()
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that you must call the <code>complete()</code> method to terminate the connection.</p>
</div>
</div>
<div class="sect3">
<h4 id="_resuming_an_async_request">Resuming an Async Request</h4>
<div class="paragraph">
<p>You resume processing of an async request (for example to delegate to view rendering) by using the <code>dispatch</code> method of the <code>AsyncContext</code> class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">index</span>() {
    <span class="keyword">def</span> ctx = startAsync()
    ctx.start {
        <span class="comment">// do working</span>
        ...
        <span class="comment">// render view</span>
        ctx.dispatch()
    }
}</code></pre>
</div>
</div>
</div>


                <div style="clear:both;margin-top:15px;"></div>
                
                    <div class="toc-item prev-left"><a href="../guide/webServices.html">&lt;&lt; <strong>10</strong><span>Web Services</span></a></div>
                
                    <div class="toc-item next-right"><a href="../guide/validation.html"><strong>12</strong><span>Validation</span> >></a></div>
                
                <div style="clear:both"></div>
            </div>
        </td>
        <td id="col2">
            <div class="local clearfix">
                <div class="local-title">
                    <a href="../guide/index.html" target="mainFrame">Quick Reference</a>
                    <span class="toggle">(<a href="#" onclick="localToggle(); return false;">hide</a>)</span>
                </div>
                <div class="menu">
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Command Line</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Command%20Line/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/bug-report.html">bug-report</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/clean.html">clean</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/compile.html">compile</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/console.html">console</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-app.html">create-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-command.html">create-command</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-controller.html">create-controller</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-domain-class.html">create-domain-class</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-functional-test.html">create-functional-test</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-hibernate-cfg-xml.html">create-hibernate-cfg-xml</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-integration-test.html">create-integration-test</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-interceptor.html">create-interceptor</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-plugin.html">create-plugin</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-profile.html">create-profile</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-script.html">create-script</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-service.html">create-service</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-taglib.html">create-taglib</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-unit-test.html">create-unit-test</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/dependency-report.html">dependency-report</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/docs.html">docs</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/generate-all.html">generate-all</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/generate-controller.html">generate-controller</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/generate-views.html">generate-views</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/help.html">help</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/install-templates.html">install-templates</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/list-plugins.html">list-plugins</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/list-profiles.html">list-profiles</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/package-plugin.html">package-plugin</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/package.html">package</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/plugin-info.html">plugin-info</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/profile-info.html">profile-info</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/run-app.html">run-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/run-command.html">run-command</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/run-script.html">run-script</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/schema-export.html">schema-export</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/shell.html">shell</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/stats.html">stats</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/stop-app.html">stop-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/test-app.html">test-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/war.html">war</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Constraints</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Constraints/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Constraints/attributes.html">attributes</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/bindable.html">bindable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/blank.html">blank</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/creditCard.html">creditCard</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/email.html">email</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/inList.html">inList</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/matches.html">matches</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/max.html">max</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/maxSize.html">maxSize</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/min.html">min</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/minSize.html">minSize</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/notEqual.html">notEqual</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/nullable.html">nullable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/range.html">range</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/scale.html">scale</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/size.html">size</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/unique.html">unique</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/url.html">url</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/validator.html">validator</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/widget.html">widget</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Controllers</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Controllers/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Controllers/actionName.html">actionName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/allowedMethods.html">allowedMethods</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/bindData.html">bindData</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/chain.html">chain</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/controllerName.html">controllerName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/defaultAction.html">defaultAction</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/errors.html">errors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/flash.html">flash</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/forward.html">forward</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/grailsApplication.html">grailsApplication</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/hasErrors.html">hasErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/namespace.html">namespace</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/params.html">params</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/redirect.html">redirect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/render.html">render</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/request.html">request</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/respond.html">respond</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/response.html">response</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/responseFormats.html">responseFormats</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/scope.html">scope</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/servletContext.html">servletContext</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/session.html">session</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/withForm.html">withForm</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/withFormat.html">withFormat</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Database Mapping</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Database%20Mapping/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/autoImport.html">autoImport</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/autoTimestamp.html">autoTimestamp</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/batchSize.html">batchSize</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/cache.html">cache</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/cascade.html">cascade</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/column.html">column</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/comment.html">comment</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/discriminator.html">discriminator</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/dynamicInsert.html">dynamicInsert</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/dynamicUpdate.html">dynamicUpdate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/fetch.html">fetch</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/id.html">id</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/ignoreNotFound.html">ignoreNotFound</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/indexColumn.html">indexColumn</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/insertable.html">insertable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/joinTable.html">joinTable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/lazy.html">lazy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/order.html">order</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/sort.html">sort</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/table.html">table</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/type.html">type</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/updateable.html">updateable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/version.html">version</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Domain Classes</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Domain%20Classes/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/addTo.html">addTo</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/attach.html">attach</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/belongsTo.html">belongsTo</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/clearErrors.html">clearErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/constraints.html">constraints</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/count.html">count</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/countBy.html">countBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/createCriteria.html">createCriteria</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/delete.html">delete</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/discard.html">discard</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/embedded.html">embedded</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/errors.html">errors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/executeQuery.html">executeQuery</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/executeUpdate.html">executeUpdate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/exists.html">exists</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/fetchMode.html">fetchMode</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/find.html">find</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findAll.html">findAll</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findAllBy.html">findAllBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findAllWhere.html">findAllWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findBy.html">findBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findOrCreateBy.html">findOrCreateBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findOrCreateWhere.html">findOrCreateWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findOrSaveBy.html">findOrSaveBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findOrSaveWhere.html">findOrSaveWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findWhere.html">findWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/first.html">first</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/get.html">get</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/getAll.html">getAll</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/getDirtyPropertyNames.html">getDirtyPropertyNames</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/getPersistentValue.html">getPersistentValue</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/hasErrors.html">hasErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/hasMany.html">hasMany</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/hasOne.html">hasOne</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/ident.html">ident</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/instanceOf.html">instanceOf</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/isAttached.html">isAttached</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/isDirty.html">isDirty</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/last.html">last</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/list.html">list</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/listOrderBy.html">listOrderBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/load.html">load</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/lock.html">lock</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/mapWith.html">mapWith</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/mappedBy.html">mappedBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/mapping.html">mapping</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/merge.html">merge</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/namedQueries.html">namedQueries</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/properties.html">properties</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/read.html">read</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/refresh.html">refresh</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/removeFrom.html">removeFrom</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/save.html">save</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/transients.html">transients</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/validate.html">validate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/where.html">where</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/whereAny.html">whereAny</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/withCriteria.html">withCriteria</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/withNewSession.html">withNewSession</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/withSession.html">withSession</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/withTransaction.html">withTransaction</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Plug-ins</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Plug-ins/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/URL%20mappings.html">URL mappings</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/codecs.html">codecs</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/controllers.html">controllers</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/core.html">core</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/dataSource.html">dataSource</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/domainClasses.html">domainClasses</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/hibernate.html">hibernate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/i18n.html">i18n</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/logging.html">logging</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/scaffolding.html">scaffolding</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/services.html">services</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/servlets.html">servlets</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Services</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Services/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Services/scope.html">scope</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Services/transactional.html">transactional</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Servlet API</h1><div class="menu-sub">
                        
                            
                            <div class="menu-item"><a href="../ref/Servlet%20API/request.html">request</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Servlet%20API/response.html">response</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Servlet%20API/servletContext.html">servletContext</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Servlet%20API/session.html">session</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Tag Libraries</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/actionName.html">actionName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/controllerName.html">controllerName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/flash.html">flash</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/pageScope.html">pageScope</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/params.html">params</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/request.html">request</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/response.html">response</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/servletContext.html">servletContext</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/session.html">session</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Tags</h1><div class="menu-sub">
                        
                            
                            <div class="menu-item"><a href="../ref/Tags/actionSubmit.html">actionSubmit</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/actionSubmitImage.html">actionSubmitImage</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/applyLayout.html">applyLayout</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/checkBox.html">checkBox</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/collect.html">collect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/cookie.html">cookie</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/country.html">country</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/countrySelect.html">countrySelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/createLink.html">createLink</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/createLinkTo.html">createLinkTo</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/currencySelect.html">currencySelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/datePicker.html">datePicker</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/each.html">each</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/eachError.html">eachError</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/else.html">else</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/elseif.html">elseif</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/external.html">external</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/field.html">field</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/fieldError.html">fieldError</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/fieldValue.html">fieldValue</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/findAll.html">findAll</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/form.html">form</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/formatBoolean.html">formatBoolean</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/formatDate.html">formatDate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/formatNumber.html">formatNumber</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/grep.html">grep</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/hasErrors.html">hasErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/header.html">header</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/hiddenField.html">hiddenField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/if.html">if</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/img.html">img</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/include.html">include</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/isAvailable.html">isAvailable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/isNotAvailable.html">isNotAvailable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/javascript.html">javascript</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/join.html">join</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/layoutBody.html">layoutBody</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/layoutHead.html">layoutHead</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/layoutTitle.html">layoutTitle</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/link.html">link</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/localeSelect.html">localeSelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/message.html">message</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/meta.html">meta</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/pageProperty.html">pageProperty</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/paginate.html">paginate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/passwordField.html">passwordField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/radio.html">radio</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/radioGroup.html">radioGroup</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/render.html">render</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/renderErrors.html">renderErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/resource.html">resource</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/select.html">select</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/set.html">set</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/sortableColumn.html">sortableColumn</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/submitButton.html">submitButton</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/textArea.html">textArea</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/textField.html">textField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/timeZoneSelect.html">timeZoneSelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/unless.html">unless</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/uploadForm.html">uploadForm</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/while.html">while</a>
                            </div>
                            
                            </div>
                    </div>
                    
                </div>
            </div>
        </td>
    </tr>
</table>

<div id="footer">
    Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
    
</div>

<script type="text/javascript" src="../js/docs.js"></script>

</body>
</html>
